babel-plugin-istanbul

What is babel-plugin-istanbul?

The babel-plugin-istanbul npm package is used to instrument your JavaScript code with Istanbul coverage. It works seamlessly with Babel and test runners like Mocha, Jest, and others to generate coverage reports. This plugin is typically used during testing to collect information about which parts of your codebase are covered by tests.

What are babel-plugin-istanbul's main functionalities?

Code Instrumentation

This feature automatically instruments your code with Istanbul coverage when it is being transpiled by Babel. The code sample shows how to apply the plugin when transforming code with Babel.

require('babel-core').transform('code', { plugins: ['istanbul'] });

Coverage Reporting

After running tests with the instrumented code, you can generate coverage reports in various formats using Istanbul's command line tool, nyc. The code sample shows how to generate a text report.

nyc report --reporter=text

Configuration Options

The plugin allows you to specify options such as excluding files or directories from being instrumented. The code sample demonstrates how to exclude all files in the 'test' directory.

{ 'plugins': [['istanbul', { 'exclude': ['test/**/*.js'] }]] }

Other packages similar to babel-plugin-istanbul

nyc

nyc is Istanbul's command line interface and can be used for instrumenting code, running tests, and generating coverage reports. It works well with subprocesses and can be used as a standalone tool without Babel.

istanbul

istanbul is the original code coverage tool that provides a JavaScript API for instrumenting code, as well as a command line tool for generating reports. It is the underlying tool that babel-plugin-istanbul and nyc are built upon.

jest

Jest is a testing framework that includes its own coverage reporting capabilities. It uses Istanbul under the hood for coverage instrumentation and can generate coverage reports without the need for additional plugins.

karma-coverage

karma-coverage is a plugin for the Karma test runner that generates code coverage reports using Istanbul. It is similar to babel-plugin-istanbul but is specifically designed to work within the Karma ecosystem.

README

babel-plugin-istanbul

A Babel plugin that instruments your code with Istanbul coverage. It can instantly be used with karma-coverage and mocha on Node.js (through nyc).

Note: This plugin does not generate any report or save any data to any file; it only adds instrumenting code to your JavaScript source code. To integrate with testing tools, please see the Integrations section.

Usage

Install it:

npm install --save-dev babel-plugin-istanbul

Add it to .babelrc in test mode:

{
  "env": {
    "test": {
      "plugins": [ "istanbul" ]
    }
  }
}

Optionally, use cross-env to set NODE_ENV=test:

{
  "scripts": {
    "test": "cross-env NODE_ENV=test nyc --reporter=lcov --reporter=text mocha test/*.js"
  }
}

Integrations

karma

It just works with Karma. First, make sure that the code is already transpiled by Babel (either using karma-babel-preprocessor, karma-webpack, or karma-browserify). Then, simply set up karma-coverage according to the docs, but don’t add the coverage preprocessor. This plugin has already instrumented your code, and Karma should pick it up automatically.

It has been tested with bemusic/bemuse project, which contains ~2400 statements.

mocha on node.js (through nyc)

Configure Mocha to transpile JavaScript code using Babel, then you can run your tests with nyc, which will collect all the coverage report.

babel-plugin-istanbul respects the include/exclude configuration options from nyc, but you also need to configure NYC not to instrument your code by adding these settings in your package.json:

  "nyc": {
    "sourceMap": false,
    "instrument": false
  },

Ignoring files

You don't want to cover your test files as this will skew your coverage results. You can configure this by providing plugin options matching nyc's exclude/include rules:

{
  "env": {
    "test": {
      "plugins": [
        ["istanbul", {
          "exclude": [
            "**/*.spec.js"
          ]
        }]
      ]
    }
  }
}

If you don't provide options in your Babel config, the plugin will look for exclude/include config under an "nyc" key in package.json.

You can also use istanbul's ignore hints to specify specific lines of code to skip instrumenting.

Source Maps

By default, this plugin will pick up inline source maps and attach them to the instrumented code such that code coverage can be remapped back to the original source, even for multi-step build processes. This can be memory intensive. Set useInlineSourceMaps to prevent this behavior.

{
  "env": {
    "test": {
      "plugins": [
        ["istanbul", {
          "useInlineSourceMaps": false
        }]
      ]
    }
  }
}

If you're instrumenting code programatically, you can pass a source map explicitly.

import babelPluginIstanbul from 'babel-plugin-istanbul';

function instrument(sourceCode, sourceMap, fileName) {
  return babel.transform(sourceCode, {
    filename,
    plugins: [
      [babelPluginIstanbul, {
        inputSourceMap: sourceMap
      }]
    ]
  })
}

Credit where credit is due

The approach used in babel-plugin-istanbul was inspired by Thai Pangsakulyanont's original library babel-plugin-__coverage__.